Live MQTT controle

tip

De Live MQTT-controller is bedoeld voor live controle. Voor het verzenden van planningen vooraf, zie in plaats daarvan Scheduled MQTT Control.

Deze gids helpt je bij het configureren van MQTT op je SmartgridOne Controller om batterij- en zonnepaneleninstallaties op afstand te bedienen en te controleren.

Wat je nodig hebt

1. SmartgridOne Controller met internetverbinding.
2. MQTT-gegevens: Dit kan worden aangevraagd door een e-mail te sturen naar support@eniris.be.
3. Python ontwikkelomgeving (of een andere MQTT-client). Deze gids gebruikt een eenvoudig voorbeeld geschreven in Python om je op gang te helpen met MQTT en het verzenden van opdrachten. We raden aan om Python te gebruiken voor het gebruiksgemak, maar elke andere MQTT-client is ondersteund.

Extra informatie

MQTT is een snel communicatieprotocol via internet. Het is een publiceer/abonneer berichten systeem, dat een directe verbinding mogelijk maakt tussen jouw machine en de SmartgridOne Controller. Je activa zijn ingedeeld in groepen voor zonnepanelen, batterijen, EV en HVAC.

Eerste configuratie (startpunt voor nieuwe gebruikers)

Ik heb een SmartgridOne Controller die ik wil instellen voor MQTT Remote Control.

1. Controleer je netwerk

Zorg ervoor dat je netwerk mqtt-netwerkverkeer via poort 1883 toestaat. Dit kun je doen met het commando:

nc -zv mqtt.eniris.be 1883

Wanneer dit commando niet beschikbaar is, kun je alternatieve deze python-code downloaden en uitvoeren.

Bij twijfel, raadpleeg je netwerkingenieur of gebruik tijdelijk de 4G/5G-hotspot van je telefoon wanneer er verbindingsfouten optreden.

notitie

Wanneer poort 1883 niet toegankelijk is vanuit je netwerk, bieden we een back-up op poort 80. Dit kan later in deze handleiding in je MQTT-client worden geconfigureerd.

2. Voeg je apparaten toe

Log in op de inbedrijfstellingsinterface en zorg ervoor dat de apparaten zijn toegevoegd aan de SmartgridOne Controller.

3. Voeg het MQTT-externe signaal toe

4. Schakel het MQTT-externe signaal in

Het veld 'VPP ID' moet leeg worden gelaten.

De timeout van het fallbackmechanisme vertelt de SmartgridOne Controller hoe lang het moet wachten op nieuwe opdrachten. Wanneer de SmartgridOne Controller stopt met het ontvangen van opdrachten, pakt deze automatisch de standaardstrategie na deze timeout.

Selecteer daarna alle apparaten die je wilt opnemen in MQTT Remote Control.

5. Externe signaal is toegevoegd

De MQTT Remote Control-interface is nu geactiveerd op de SmartgridOne Controller.

We zijn nu klaar om enkele basisopdrachten te verzenden met een eenvoudig voorbeeld. De Status-kolom vertelt je of een opdracht actief is.

Python demo script

Een goed startpunt zou zijn om je nieuw opgezette integratie te testen met een eenvoudig voorbeeld.

Deze testcode doet een eenvoudige taak door continu de volgende opdrachten te verzenden:

• Batterij: Opladen op 5 kW
• Zonne-energie: Stel vermogen in op 0 kW

De SmartgridOne Controller reageert continu met een 'feedback'-bericht dat de waargenomen net- en activa-vermogenwaarden bevat. Deze functie is ook opgenomen in dit voorbeeld.

Download het onderstaande bestand in je favoriete Python IDE. Vul je serienummer en MQTT-gegevens in en voer het script uit:

Wanneer het bovenstaande succesvol is, kun je verder gaan met het verzenden van andere soorten opdrachten. Alle opdrachten worden beschreven in onze MQTT Remote Control-documentatie.

MQTT Documentatie voor het verzenden van opdrachten

Deze sectie beschrijft het MQTT-berichtformaat en de payloadvereisten voor het op afstand bedienen van stroombeleid op apparaten binnen het netwerk van de SmartgridOne Controller.

MQTT Onderwerp

Het MQTT-onderwerp dat wordt gebruikt voor het verzenden van opdrachten is als volgt gestructureerd:

standard1/rp_one_s/remoteControlMetrics/'controller SN'

Waarbij 'controller SN' vervangen moet worden door het werkelijke serienummer van de SmartgridOne Controller die je wilt bedienen.

MQTT Payloadstructuur

Opdrachten worden verzonden als JSON-payloads. De payloadstructuur is ontworpen om verschillende energiebeheersbeleid en instelwaarden voor verschillende componenten van het slimme net te specificeren. Hier is de schets van de payload met gedetailleerde veldbeschrijvingen:

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": "<Unix Timestamp>",
    "fields": {
        "<Component Policy>": "<Policy Type>",
        "<Component Power Setpoint>": <Setpoint in watts>
    }
}

Veldbeschrijving

tip

Meerdere apparaattypen (bijv. batterijen + zonnepanelen) kunnen tegelijkertijd worden aangestuurd.

• extraTags (Object):
  • nodeId (String): Een unieke identifier voor de node binnen het netwerk van de SmartgridOne Controller. Dit is gelijk aan je serienummer, gevolgd door '_site_0' voor de meeste SmartgridOne Controller-apparaten.
• time (Integer): Unix-timestamp in seconden die aangeeft wanneer het bericht wordt verzonden.
• fields (Object):
  • <Component>_policy (String): Beleidsvorm voor de component. Dit is optioneel en als het niet is gespecificeerd, zal het systeem terugvallen op de standaardinstelling van de SmartgridOne Controller.
  • <Component>_power_setpoint_w (Float): Gewenste power setpoint in watts voor de component. Dit is optioneel en alleen relevant als een bijbehorend beleid is gespecificeerd.

Componenten en Beleid

info

Activa van hetzelfde type (bijv. twee batterijen) worden gecombineerd als één component. Wanneer er bijvoorbeeld twee 5 kWh-batterijen zijn geïnstalleerd, wordt dit behandeld als één 10 kWh-batterij.

Elke component in het fields-object kan een beleid en een power setpoint bevatten. De volgende componenten kunnen worden aangestuurd:

• solar_policy en solar_power_setpoint_w:

  • Beheert het beleid en de setpoint van de zonne-energieproductie. Ondersteunde beleidsvormen:
    • Beleid setpoint: Stel het maximale vermogen in dat door alle aangesloten zonne-installaties samen wordt geproduceerd. Veld solar_power_setpoint_w moet worden ingesteld op de productie vermogenlimiet in watts.
    • Beleid feed-in-restrictie: Produceer op vol vermogen, volgens de huidige netlimieten.
    • Beleid kosten: Maakt kostenminimalisatie van de dagprijs (EPEX Spotmarkt) op de zonneproductie mogelijk. Wanneer er negatieve injectieprijzen optreden, beperken we de productie tot eigen consumptie. Wanneer zowel de afname- als injectieprijs negatief zijn, schakelen we alle zonne-installaties uit. Veld solar_power_setpoint_w wordt genegeerd.
    • Beleid uit: Schakelt alle interactie voor alle zonne-activa uit. Waarschuwing: limieten worden in deze modus niet bewaakt. Veld solar_power_setpoint_w wordt genegeerd.

• storage_policy en storage_power_setpoint_w:

• Beheert het beleid van het energiesopsysteem en de ontlaad- of laad snelheid.

  • Beleid setpoint: Stel het totale laadvermogen in (positieve setpoint) of ontlaadvermogen (negatieve setpoint) voor de groep batterijen. Wanneer meerdere batterijen zijn aangesloten, wordt de setpoint verdeeld over het beschikbare laad/ontlaadvermogen om de batterijen gelijkmatig te belasten. Veld storage_power_setpoint_w is ingesteld op het gewenste batterijvermogen.
  • Beleid kosten: Maakt kostenoptimalisatie voor dagvooruit (EPEX Spotmarkt) mogelijk op de batterijen, door deze op de goedkope uren op te laden en de energie in de dure uren te gebruiken. Veld storage_power_setpoint_w wordt genegeerd.
  • Beleid zelfverbruik: Maakt een eenvoudig zelfverbruik algoritme op de batterijen mogelijk. Overtollige zonne-energie wordt tijdens het zonlicht in de batterij opgeslagen en wanneer de zon ondergaat, wordt energie uit de batterij gehaald. Veld storage_power_setpoint_w wordt genegeerd.
  • Beleid uit: Deactiveert alle interactie voor alle batterijactiva. Waarschuwing: limieten worden in deze modus niet bewaakt. Veld storage_power_setpoint_w wordt genegeerd.

• heat_pump_policy:

  • Schakelt de warmtepompsystemen aan/uit. De minimale en maximale aanlooptijden worden altijd gerespecteerd.
    • Beleid kosten: Maakt kostenoptimalisatie voor dagvooruit (EPEX Spotmarkt) mogelijk op de warmtepompen. Het lokale dynamische prijsalgoritme bepaalt de beste aanlooptijden.
    • Beleid zelfverbruik: Zet de warmtepompen aan als er een overschot aan zonne-energie wordt geproduceerd.
    • Beleid power_off: Zet de warmtepompen uit.
    • Beleid power_on: Zet de warmtepompen aan.

• switched_load_policy:

  • Schakelt relaisgestuurde systemen aan/uit. Dit kan het ingebouwde relais of netwerkverbonden relais zijn.
    • Beleid kosten: Maakt kostenoptimalisatie voor dagvooruit (EPEX Spotmarkt) mogelijk op het relais.
    • Beleid zelfverbruik: Zet het relais aan als er een overschot aan zonne-energie wordt geproduceerd.
    • Beleid power_off
    • Beleid power_on

• variable_power_load_policy en variable_power_load_power_setpoint_w:

  • Beheert het energieverbruikbeleid van elektrische voertuigen en het setpoint.
    • Beleid setpoint: Stel het totale laadvermogen voor de groep EV's in. Veld variable_power_load_power_setpoint_w is ingesteld op het gewenste laadvermogen.
    • Beleid kosten: Maakt kostenoptimalisatie voor dagvooruit (EPEX Spotmarkt) mogelijk op de batterijen, door deze op de goedkope uren op te laden. Veld variable_power_load_power_setpoint_w wordt genegeerd.
    • Beleid zelfverbruik: Maakt laden mogelijk als er een overschot aan zonne-energie wordt geproduceerd. Veld variable_power_load_power_setpoint_w wordt genegeerd.
    • Beleid uit: Deactiveert alle interactie voor alle EV-activa. Veld variable_power_load_power_setpoint_w wordt genegeerd.

• site_policy en site_power_setpoint_w:

  • Beheert de exportlimieten van de site.
    • Beleid export: Stel de exportlimiet voor de site in. Veld site_power_setpoint_w is ingesteld op de exportlimiet.
    • Beleid standaard: Herstelt de site limiet naar het standaard exportvermogen, ingesteld in de controllerconfiguratie.

Apparatenbeheer

Specifieke apparaten kunnen ook worden beheerd, in plaats van groepen apparaten op basis van hun types. Het bericht is identiek gestructureerd:

• nodeId_policy en nodeId_power_setpoint_w

Wanneer twee commando's naar hetzelfde activa worden verzonden (bijvoorbeeld één apparaat-specifiek commando naar een zonnestral inverter, en een commando naar alle zonne-apparaten), zal de apparaat-specifieke controle methode voorkeur krijgen boven de controle op basis van apparaattype.

Failovergedrag

Voor elk component, als het _beleid en _power_setpoint_w niet zijn gespecificeerd, zal het systeem automatisch het fallback-beleid gebruiken dat is geconfigureerd in de SmartgridOne Controller. Dit zorgt ervoor dat elk apparaat of apparaatgroep veilig opereert en blijft functioneren, zelfs als specifieke instructies niet zijn gegeven.

Als er helemaal geen commando wordt verzonden, worden na 60 seconden (of de geconfigureerde time-outperiode) de standaardbeleidslijnen voor activa opnieuw geactiveerd.

Voorbeeldpayload

Hieronder staat een voorbeeld van een payload om verschillende beleidslijnen en setpoints in te stellen:

{
    "extraTags": {
        "nodeId": "OM12404080000000000_site_0"
    },
    "time": 1714652046,
    "fields": {
        "solar_policy": "setpoint",
        "solar_power_setpoint_w": 5000,
        "storage_policy": "setpoint",
        "storage_power_setpoint_w": -5000
    }
}

In dit voorbeeld is het zonne-energie ingesteld om tot 5000 watt te genereren, en het energieopslagsysteem is ingesteld om te laden of ontladen met een snelheid van 5000 watt, afhankelijk van het teken van de setpointwaarde. Als ofwel het solar_policy of storage_policy werd weggelaten, zou het respectieve apparaat terugvallen naar de standaardinstellingen die zijn bepaald door de SmartgridOne Controller.

MQTT-documentatie voor het ontvangen van feedback

Dit gedeelte schetst de structuur en inhoud van de feedbackberichten die door de SmartgridOne Controller via MQTT worden verzonden. Deze berichten worden gepubliceerd naar het onderwerp standard1/outbound/remoteControlMetrics/feedback/<Controller SN> nadat een commando is verwerkt.

MQTT Feedback Onderwerp

Het feedback MQTT-onderwerp is als volgt gestructureerd:

standard1/outbound/remoteControlMetrics/feedback/<Controller SN>

Waarbij <Controller SN> moet worden vervangen door het serienummer van de SmartgridOne Controller die de feedback verzendt.

MQTT Feedback Payload Structuur

Feedbackberichten zijn opgemaakt als JSON-payloads. Deze payloads bieden gedetailleerde feedback over de status van het systeem na het toepassen van de setpoint-commando's, rekening houdend met de grid/apparaatlimieten. Hieronder is de structuur van de feedbackpayload met beschrijvingen van de velden:

{
    "time": "<Unix Tijdstempel>",
    "data": {
        "state": {
            "grid": {
                "active_power_W": <Grid Actief Vermogen in Watts>,
                "today_imported_energy_Wh": <Grid Geïmporteerde Energie in Watt-uren>,
                "today_exported_energy_Wh": <Grid Geëxporteerde Energie in Watt-uren>,
                "import_limit_W": <Grid Invoerlimiet in Watts>,
                "export_limit_W": <Grid Exportlimiet in Watts>,
            },
            "vpp_id": "<Identificatie van de Virtuele Energiecentrale>",
            "storage": {
                "energy_stored_Wh": <Energie Opgeslagen in Watt-uren>,
                "energy_capacity_Wh": <Totale Energiecapaciteit in Watt-uren>,
                "mean_soc_perc": <Gemiddelde Staat van Lading Percentage>,
                "active_power_W": <Actief Vermogen in Watts>,
                "executed_power_W": <Vermogen Setpoint Verzonden naar Apparaten in Watts>,
                "executed_policy": <Beleid Uitgevoerd door de Controller>,
                "max_charge_power_W": <Maximaal Laadvermogen in Watts>,
                "max_discharge_power_W": <Maximaal Ontlaadvermogen in Watts>,
                "today_charged_Wh": <Energie Opgeladen op de Huidige Dag in Watt-uren>,
                "today_discharged_Wh": <Energie Ontladen op de Huidige Dag in Watt-uren>,
                "nr_devices": <Aantal Gecontroleerde Opslagapparaten Geïnstalleerd>
            },
            "solar": {
                "active_power_W": <Zonne Actief Vermogen in Watts>,
                "executed_power_W": <Vermogen Setpoint Verzonden naar Apparaten in Watts>,
                "executed_policy": <Beleid Uitgevoerd door de Controller>,
                "capacity_W": <Zonnecapaciteit in Watts>,
                "today_energy_Wh": <Vandaag Geproduceerde Energie in Watt-uren>.
                "nr_devices": <Aantal Gecontroleerde Zonneapparaten Geïnstalleerd>
            },
            "heat_pump": {
                "executed_policy": <Beleid Uitgevoerd door de Controller>,
                "operation_modes": <Werkingstoestanden van de Warmtepomp>,
                "executed_power_W": <Vermogen Setpoint Verzonden naar Apparaten in Watts>,
                "nr_devices": <Aantal Gecontroleerde Warmtepomp apparaten Geïnstalleerd>
            },
            "switched_load": {
                "executed_policy": <Beleid Uitgevoerd door de Controller>,
                "devices_on": <Aantal Apparaten Aan>,
                "devices_off": <Aantal Apparaten Uit>,
                "executed_power_W": <Vermogen Setpoint Verzonden naar Apparaten in Watts>,
                "nr_devices": <Aantal Gecontroleerde Ingeschakelde Last Apparaten Geïnstalleerd>  
            }
        },
        "response_code": <Antwoordcode>
    },
    "fields": {},
    "requestTime": "<Unix Tijdstempel>",
    "time": "<Unix Tijdstempel>",
    "siteNodeId": "<Controller SN>_site_0"
}

### Velden beschrijving
- time (Integer): Unix tijdstempel dat de tijd aangeeft waarop het feedbackbericht is verzonden.
- fields (Object):
    - state (Object):
        - vpp_id (String): Identificatie voor de Virtuele Energiecentrale geassocieerd met dit apparaat.
        - grid (Object):
            - active_power_W (Float): Vertegenwoordigt het huidige actieve vermogen op het net in watts.
            - today_imported_energy_Wh (Float): De totale energie die vandaag van het net is genomen in watt-uren. Opmerking: Vandaag wordt aangegeven in UTC-tijd.
            - today_exported_energy_Wh (Float): De totale energie die vandaag terug in het net is geïnjecteerd in watt-uren. Opmerking: Vandaag wordt aangegeven in UTC-tijd.
            - import_limit_W (Float): De net invoerlimiet in watts,
            - export_limit_W (Float): De net uitvoerlimiet in watts,
        - storage (Object):
            - energy_stored_Wh (Float): Huidige hoeveelheid energie opgeslagen in watt-uren.
            - energy_capacity_Wh (Float): Totale energiecapaciteit van het opslagsysteem in watt-uren.
            - mean_soc_perc (Float): Laadstatus als percentage. Dit is het gewogen gemiddelde van alle aangesloten batterijen. (wanneer meerdere batterijen zijn aangesloten: bijv. batterij 'a' heeft een energiecapaciteit van 10 kWh en een laadpercentage van 20%; batterij 'b' heeft een energiecapaciteit van 20 kWh en een laadpercentage van 50%, dan is het mean_soc_perc 40%)
            - active_power_W (Float): Huidig actieve vermogen voor het opslagsysteem in watts, toont laad- of ontlaadsnelheid.
            - max_charge_power_W (Float): Maximale vermogen waartegen de opslag kan worden geladen.
            - max_discharge_power_W (Float): Maximale vermogen waartegen de opslag kan worden ontladen.
            - executed_power_W (Float): De som van het totale vermogen dat is aangevraagd om (te) laden of ontladen van de opslagactiva, verzonden door ons controle-algoritme. Alleen van toepassing als het 'follow_setpoint'-beleid actief is.
            - executed_policy (Str): De beleidsmaatregelen die zijn toegepast op de controleerbare elementen.
            - today_charged_Wh (Float): De totale energie die vandaag in de controleerbare batterijactiva is geladen. Opmerking: Vandaag wordt aangegeven in UTC-tijd.
            - today_charged_Wh (Float): De totale energie die vandaag in de controleerbare batterijactiva is geladen. Opmerking: Vandaag wordt aangegeven in UTC-tijd.
            - today_discharged_Wh (Float): De totale energie die vandaag uit de controleerbare batterijactiva is ontladen. Opmerking: Vandaag wordt aangegeven in UTC-tijd.
            - nr_devices (Int): Het aantal controleerbare batterijactiva.
        - solar (Object):
            - active_power_W (Float): Huidig actieve vermogen gegenereerd door zonnepanelen in watts.
            - capacity_W (Float): Totale capaciteit van het zonne-energiesysteem in watts.
            - executed_power_W (Float): De som van het totale vermogen dat is aangevraagd van de zonneactiva, verzonden door ons controle-algoritme. Alleen van toepassing als het 'follow_setpoint'-beleid actief is.
            - executed_policy (Str): De beleidsmaatregelen die zijn toegepast op de controleerbare elementen.
            - today_energy_Wh (Float): De totale energie geproduceerd uit de controleerbare zonneactiva vandaag. Opmerking: Vandaag wordt aangegeven in UTC-tijd.
            - nr_devices (Int): Het aantal controleerbare zonneactiva.
        - heat_pump (Object):
            - executed_policy (Str): De beleidsmaatregelen die zijn toegepast op de controleerbare elementen.
            - operation_modes (Str): De modus van de warmtepomp (Blokkering modus, Boostmodus, Zelfbediening modus)
            - executed_power_W (Float): Het verwachte vermogen dat het momenteel gebruikt.
            - nr_devices (Int): Het aantal controleerbare warmtepompen.
        - switched_load (Object):
            - executed_policy (Str): De beleidsmaatregelen die zijn toegepast op de controleerbare elementen.
            - devices_on (Int): Het aantal apparaten aan.
            - devices_off (Int): Het aantal apparaten uit.
            - executed_power_W (Float): Het vermogen dat het momenteel gebruikt (indien beschikbaar).
            - nr_devices (Int): Het aantal controleerbare aan/uit ingeschakelde lasten.
        - nodeId (Object):
            - Indien een nodeId is opgenomen in de opdracht, zal de feedback de bijbehorende status van het apparaat bevatten.
    - response_code (Int):
        - Geeft de status van de operatie aan. Een response_code van 0 betekent doorgaans succes, terwijl andere waarden verschillende soorten fouten of statusinformatie kunnen aangeven (deze moeten in een aparte verwijzing worden gedetailleerd).

### Voorbeeld Feedback Payload
Hier is een voorbeeld van een feedbackbericht na een opdracht om verschillende vermogensinstellingen in te stellen:

<ClickableImage src="/img/generic/mqtt-example-feedback.png" alt="Afbeelding 1" maxWidth="450px" />

Deze feedback toont de huidige operationele staat van het systeem na de uitvoering van de instelpunt, waarbij de effecten op zonne-opwekking, opslag en interactie met het netwerk worden aangegeven.

## Ondersteunde MQTT Versies en Gedrag bij Niet-Autoriseerde Onderwerpen
Bij het gebruik van MQTT is het belangrijk om rekening te houden met de verschillen in specificaties tussen versies 3.1, 3.1.1 en 5.0, met name met betrekking tot het gedrag van de broker wanneer clients naar niet-autoriseerde onderwerpen publiceren.

Volgens de MQTT 3.1.1 specificatie (zie OASIS MQTT 3.1.1 Specificatie, sectie MQTT-3.3.5-2), moet een broker de verbinding beëindigen zodra een client een PUBLISH naar een onderwerp verzendt waarvoor het geen toestemming heeft. Dit gedrag kan leiden tot onvoorziene ontkoppelingen voor clients die proberen te publiceren naar verkeerd geconfigureerde of niet-autoriseerde onderwerpen.

In MQTT 3.1 is deze vereiste niet aanwezig. Wanneer een client naar een niet-geautoriseerd onderwerp publiceert onder deze versie, negeert de broker meestal het bericht (stille annulering) zonder de verbinding te beëindigen. Dit maakt MQTT 3.1 in sommige gevallen geschikter wanneer robuustheid tegen configuratiefouten of tijdelijk ontbrekende toestemming belangrijker is dan strikte beveiligingshandhaving.

Hoewel MQTT 5.0 de mogelijkheid introduceert om met redencodes te werken (zoals PUBACK met een afwijsreden), vereist dit ondersteuning aan zowel de client- als serverzijde. Migreren naar MQTT 5.0 brengt dus extra implementatie-inspanningen met zich mee.

__Gevolgen van het Negeren van Compatibiliteit:__
Als een client verbinding maakt met MQTT 3.1.1 en probeert berichten te publiceren naar ongeautoriseerde onderwerpen, zal de broker de sessie abrupt beëindigen. Dit kan leiden tot instabiliteit, verlies van connectiviteit of een verhoogde belasting door herhaalde reconnectpogingen.

__Aanbevolen Benadering:__
Voor systemen waarbij clients (tijdelijk) proberen te publiceren naar ongeautoriseerde onderwerpen, of waarbij foutafhandeling niet strikt is geïmplementeerd, raden we aan om MQTT 3.1 te gebruiken. Dit zorgt voor stabielere verbindingen en voorkomt onbedoelde loskoppelingen tijdens runtime.